fix(driver-sql): schema drift reports a single-value JSON-class field on a stale text column - #16073

Fixes #15771

The defect was a FORK, not a missing rule

The driver decides a column's type with one predicate and reported drift about it with another:

sql-driver.ts:16085   col = JSON_COLUMN_TYPES.has(type) ? this.jsonColumn(table, name) : table.string(name);
sql-driver.ts:16301   return JSON_COLUMN_TYPES.has(type) || !!field.multiple;   the WRITER
schema-drift.ts:944   const declaresJsonColumn = field.multiple === true;       the DETECTOR

So a SINGLE-value JSON-class field — file, image, avatar, video, audio, location, address, composite, record, vector, json, and the option families — sitting on a varchar/text column was written as JSON by the writer and did not exist to the differ. syncSchema is additive and never migrates a column's type, so the divergence was permanent, and nothing else reports it, so it was silent.

This PR deletes the fork: the detector now reads the writer's own predicate. No new criterion was invented.

Reproduction, before and after

One diffManagedTable call per type, character varying(2048) column, both enforcing dialects:

BEFORE                                                   AFTER
single-value file     / postgres : findings=0            findings=1  manual_column_type_change
single-value file     / mysql    : findings=0            findings=1  manual_column_type_change
single-value location / postgres : findings=0            findings=1  manual_column_type_change
single-value location / mysql    : findings=0            findings=1  manual_column_type_change
multi-value file      / postgres : findings=1  (control) findings=1  (control, unchanged)
JSON-class spec types written as JSON but NOT detected: 15 of 15   ->  0 of 15

The multiple: true row is the firing control in the same run: the differ was working, and this whole population was invisible to it.

The message SPLITS, because the shipped remedy is wrong for half of it

os migrate multi-value-columns repairs a stale column by WRAPPING each stored value in a one-element JSON array (json_build_array(col) on Postgres, JSON_ARRAY(col) on MySQL). That is right for a field whose value is an array and wrong for one whose value is a scalar or an object. Measured with the command's own planner, on a single-value finding carrying the multi-value message:

targets: 1  refusals: 0   dialect: postgres
  ALTER TABLE "proj_task" ALTER COLUMN "doc" TYPE json USING (CASE ... ELSE json_build_array("doc") END)

And measured on an in-memory SQLite cell, what that would do to the value:

ok      : value="file_01HXYZ"          typeof=string  isArray=false     what ObjectStack stores
wrapped : value=["\"file_01HXYZ\""]    typeof=object  isArray=true      after the array remedy

So both populations are REPORTED and only one is offered the remedy:

• Array-valued (multiple: true, plus the inherently-multi option types, whose value is a list with or without the flag) keeps its message character for character. That is a contract, not a style choice: planStaleColumnTargets recovers the dialect by testing message.includes(manualJsonConversionSql(d, table, column)), so a reworded message makes the command refuse every finding. Proven against origin/main itself while writing the change — the whole entry, message included, compared equal for lookup, string and file with multiple: true, on both dialects.
• Single-value carries a message of its own that names neither the command nor the statement, explains why the automated route is withheld, and describes the by-hand conversion. The same probe therefore recovers no dialect and the command REFUSES the entry with remedy_not_recognized — its designed branch for a message it cannot read — instead of running array SQL over scalar rows. Pinned from both sides.

⛔ No new remedy DDL was invented. manualJsonConversionSql's two existing forms are EXECUTED against live servers by the suite, and two of their arms were corrected only by running an earlier version against a live database; there is no live Postgres or MySQL cell in this container, so a third unmeasured statement is not something this PR ships. The remedy split is filed as #16072 with the three options and what each costs.

SQLite: the reverse control, re-measured

On SQLite the harm is not reachable, and that is a measurement rather than a scoping convenience. On an in-memory cell, a single-value file field over the stale varchar(2048) column and over the driver's own column:

stale column type : varchar        fresh column type : text
stale RAW stored  : "file_01HXYZ"  fresh RAW stored  : "file_01HXYZ"     byte-identical
stale read-back   : "file_01HXYZ"  fresh read-back   : "file_01HXYZ"     identical
sqlite detectManagedDrift manual_column_type_change: []

The read path parses a textual column regardless of what it calls itself, so there is nothing to corrupt and nothing to report. The pin keeps that leg as its reverse control: without it, every positive assertion above is equally satisfied by a detector that always reports.

What the consequence chain is, and is NOT

The card's downstream chain is REASONED FROM CODE and is not upgraded here: formatInput JSON.stringifys every isJsonField value unconditionally, and the read-side JSON.parse lives only inside the isSqlite arm of formatOutput, so on Postgres/MySQL a varchar column returns the quoted text verbatim, isFileIdToken refuses it, the read resolver never expands it and the ownership hooks never claim it. There is no live Postgres or MySQL cell in this container, so that chain is stated exactly as the card stated it. What IS measured here is the stored form (SQLite, byte-for-byte), the detector's before/after verdicts, and the planner's behaviour.

Also corrected by the same predicate: a single-value JSON-class field declaring a maxLength over a wider varchar column used to be reported as narrow_varchar at category destructive, inviting os migrate apply --allow-destructive to rewrite the column to a narrower varchar — the opposite of the repair it needs. It is now reported once, as the base-type divergence. Pinned.

Scope

⛔ packages/cli/src/commands/generate.ts is untouched: the VARCHAR(2048)-vs-json-column divergence in the generated migration is #15041's subject and that file's own docblock already acknowledges it. This change is only about the detector, and the blind spot it closes applies to every single-value member of the writer's set whichever way #15041 goes. Out of scope here, still open: #15041, and #16072 for the remedy split.

Published surface — the dist/index.d.ts ablation

Built at head, swapped schema-drift.ts back to origin/main, rebuilt, diffed the built dist/index.d.ts, restored byte-exact:

ON-DISK PROOF  new-symbol hits=0 (expect 0) · reverted-line hits=1 (expect 1) · blob differs
dist preflight (--absent) exit=0        the mutation reached dist/
ABLATED driver-sql pins exit=1          9 failed | 22 passed | 3 skipped
ABLATED cli pin       exit=1            1 failed | 11 passed
RESTORE PROOF  blob == HEAD blob · git diff HEAD empty
dist preflight (present) exit=0         marker present in 2 built files
RESTORED driver-sql pins exit=0         31 passed | 3 skipped
RESTORED cli pin      exit=0            12 passed
dist/index.d.ts diff (origin/main build vs head build): 0 changed lines

Both limbs of the surface question, stated separately:

• Type/export surface: unchanged. The built dist/index.d.ts is byte-identical between the two builds. JSON_COLUMN_FIELD_TYPES is module-exported so this package's own suites can pin it and is deliberately NOT added to index.ts — the same call UNBOUNDED_TEXT_FIELD_TYPES and MULTI_VALUE_COLUMN_REMEDY_COMMAND make.
• Accept/reject behaviour: nothing is newly accepted or rejected. This widens a DIAGNOSTIC VERDICT's population. No request is admitted or refused, no write is validated, no published accept-set moves. The one real downstream consequence — os migrate multi-value-columns now meets a population it never met — is handled by routing that population into the command's refusal branch, so nothing new is executed there either.

Tests

New: packages/drivers/driver-sql/src/schema-drift.json-column-parity.test.ts holds the differ's JSON-class predicate equal to the writer's isJsonField over every FieldType the spec declares, in both directions, and compares the two halves where they actually meet — through diffManagedTable's output rather than between two constants. Extended: schema-drift.base-type-mismatch.test.ts (the single-value cases on both enforcing dialects, the SQLite non-finding as the reverse control, the whole-vocabulary sweep, the message split in both directions, the byte-identity of the array message, and the narrow_varchar regression) and packages/cli/src/commands/migrate/multi-value-columns.dialect-probe.test.ts (the refusal, with an array-valued target as the contrast in the same run).

Verified at 784956909:

pnpm --filter @objectstack/driver-sql test          155 passed | 9 skipped (164 files) · 2389 passed | 140 skipped
pnpm --filter @objectstack/cli exec vitest run (9 drift-consumer files)   9 passed · 84 passed
pnpm --filter @objectstack/driver-sql typecheck     exit 0
pnpm --filter @objectstack/cli typecheck            exit 0  (tsc --listFiles confirms both edited test files are in the program)
gate family from `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` at 784956909:
  43 of 45 exit 0, plus `pnpm check:nul-bytes` exit 0
  check:dual-build-cjs-loads and check:i18n-coverage exit 3 = "COULD NOT MEASURE / this is NOT a pass:
  nothing was measured" — both need a full workspace build this worktree does not have. Not findings;
  CI builds the workspace and measures them there.

Generated by Claude Code